Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 4 - Dialog Manager Reference / Dialog Manager Functions

Creating Dialog Boxes /

NewFeaturesDialog

NEW WITH THE APPEARANCE MANAGER

Creates a dialog box from information passed in memory.

pascal DialogPtr NewFeaturesDialog (
                     void *inStorage,
                     const Rect *inBoundsRect,
                     ConstStr255Param inTitle,
                     Boolean inIsVisible,
                     SInt16 inProcID,
                     WindowPtr inBehind,
                     Boolean inGoAwayFlag,
                     SInt32 inRefCon,
                     Handle inItemListHandle,
                     UInt32 inFlags);

inStorage

A pointer to the memory for the dialog structure. If you set this parameter to nil, the Dialog Manager automatically allocates a nonrelocatable block in your application heap.

inBoundsRect

A pointer to a rectangle, given in global coordinates, that determines the size and position of the dialog box; these coordinates specify the upper-left and lower-right corners of the dialog box.

inTitle

A pointer to a text string used for the title of a modeless or movable modal dialog box. You can specify an empty string (not nil) for a title bar that contains no text.

inIsVisible

A flag that specifies whether the dialog box should be drawn on the screen immediately. If you set this parameter to false, the dialog box is not drawn until your application uses the Window Manager function ShowWindow, described in "Displaying Windows", to display it.

inProcID

The window definition ID for the type of dialog box, specified with constants defined by the Window Manager. Use the kWindowModalDialogProc constant to specify modal dialog boxes, the kWindowDocumentProc constant to specify modeless dialog boxes, and the kWindowMovableModalDialogProc constant to specify movable modal dialog boxes.

inBehind

A pointer to the window behind which the dialog box is to be placed on the desktop. Set this parameter to the window pointer (WindowPtr)-1L to bring the dialog box in front of all other windows.

inGoAwayFlag

A Boolean value. If true, specifies that an active modeless dialog box has a close box in its title bar.

inRefCon

A value that the Dialog Manager uses to set the refCon field of the dialog box's window structure. Your application may store any value here for any purpose. For example, your application can store a number that represents a dialog box type, or it can store a handle to a structure that maintains state information about the dialog box. You can use the Window Manager function SetWRefCon at any time to change this value in the dialog structure for a dialog box, and you can use the GetWRefCon function to determine its current value.

inItemListHandle

A handle to an item list resource for the dialog box. You can get the handle by calling the Resource Manager function GetResource to read the item list resource into memory.

inFlags

An unsigned 32-bit mask specifying the dialog box's Appearance-compliant feature flags; see "Dialog Feature Flag Constants". To establish an embedding hierarchy in a dialog box, pass kDialogFlagsUseControlHierarchy in the inFlags parameter.

function result

Returns a pointer to the new dialog box. If it doesn't create a new dialog box, returns nil.

DISCUSSION

The NewFeaturesDialog function creates a dialog box without using 'DLOG' or 'dlgx' resources. Although the inItemListHandle parameter specifies an item list ('DITL') resource for the dialog box, the corresponding dialog font table ('dftb') resource is not automatically accessed. You must explicitly set the dialog box's control font style(s) individually.

SEE ALSO

"Appearance Manager Gestalt Selector Constants".